Creates a pool of threads for your application.

OSErr CreateThreadPool (
    ThreadStyle threadStyle, 
    SInt16 numToCreate, 
    Size stackSize
);

threadStyle

The type of thread to create for this set of threads in the pool. Cooperative is the only type that you can specify. Historically, the Thread Manger supported two types of threads, preemptive and cooperative. However, due to severe limitations on their use, the Thread Manager no longer supports preemptive threads.

numToCreate

The number of threads to create for the pool.

stackSize

The stack size for this set of threads in the pool. This stack must be large enough to handle saved thread context, normal application stack usage, interrupt handling functions, and CPU exceptions. Specify a stack size of 0 to request the Thread Managerís default stack size for the specified type of thread.

function result

A result code.

DISCUSSION

The CreateThreadPool function creates the specified number of threads with the specified stack requirements. It places the threads that it creates into a pool for use by your application.

When you call CreateThreadPool, if the Thread Manager is unable to create all the threads that you specify, it does not create any at all and returns the memFullErr result code.

The threads in the pool are indistinguishable except by stack size. That is, you cannot refer to them individually. When you want to use a thread to execute some code in your application, you allocate a thread of a specific size from the pool using the NewThread function. The NewThread function assigns a thread ID to the thread and specifies the function that is the entry point to the thread.

Note that it is not strictly necessary to create a pool of threads before allocating a thread. If you wish, you can use the NewThread function to create and allocate a thread in one step. The advantage of using CreateThreadPool is that you can allocate memory for threads early in your applicationís execution before memory is used or fragmented.

Before making any calls to CreateThreadPool, be certain that you first have called the Memory Manager function MaxApplZone to extend the application heap to its limit. You must call MaxApplZone from the main application thread before any other threads in your application run.

To allocate a thread from the pool created with CreateThreadPool, use the NewThread function.

To determine how many threads in the pool are available for allocation, use the GetFreeThreadCount function. To determine how many threads of a particular stack size are available, use the GetSpecificFreeThreadCount function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.

© 2000 Apple Computer, Inc. — (Last Updated 3/8/2000)